<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<!-- 
Copyright (c) 2008 Matthew Johnson
Licensed under the MIT License (see license.txt)	
-->
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<title>ActionML Buttons</title>
<script src="Scripts/AC_RunActiveContent.js" type="text/javascript"></script>
</head>

<body>

<!-- {NAV} -->
<ul class="nav">
	<li>Markup
		<ul>
			<li><a href="getting_started.html">Getting started</a></li>
			<li><a href="attributes.html">Elements and attributes</a></li>
			<li><a href="actions.html">Events and actions</a></li>
			<li><a href="tweens.html">Tweens</a></li>
			<!--<li><a href="more_tweens.html">More tweens</a></li>-->
			<li><a href="custom_actions.html">Custom actions</a></li>
		</ul>
	</li>
	<li>Widgets
		<ul>
			<li><a href="buttons.html">Buttons</a></li>
			<li><a href="more_buttons.html">More buttons (and tabs)</a></li>
			<li><a href="filmstrip.html">Filmstrip</a></li>
			<li><a href="popup.html">Popup</a></li>
			<li><a href="drag_and_drop.html">Drag and drop</a></li>
			<li><a href="slider.html">Slider</a></li>
			<li><a href="scrollable_text.html">Scrollable text</a></li>
			<li><a href="media_controller.html">Media controller</a></li>
			<li><a href="video.html">Video</a></li>
		</ul>
	</li>
	<li>Example Media
		<ul>
			<li><a href="theories_and_assumptions/theories_and_assumptions.html">Tabs with drag and drop</a></li>
			<li><a href="group_counseling/group_counseling.html">Multiple videos with drag and drop</a></li>
		</ul>
	</li>
	<li><a href="cheatsheet.pdf">Cheatsheet</a></li>
	<li><a href="release_notes.html">Release Notes</a></li>
</ul>
<!-- {/NAV} -->

<h1>ActionML Buttons</h1>
<p>Buttons are the simplest kind of interactive element in the ActionML language.  The most common use for a button is to do something when it is clicked.  A button can also indicate focus to the user (when the user mouses over them or tabs to them with keyboard input).  Sometimes the focus indicator will be useful to display additional content.  In that case there may not be an action that takes place when a button is clicked.</p>
<h2>Creating the button symbol</h2>
<p>The first step in creating a button is to create your button symbol using the Flash authoring tool.  A button does not need to look like a button and can be anything you can place inside a movie clip.  Here is an example of a button:
<br /><img src="buttons/button_symbol.png" /><br />
Note that the button we are inside a symbol called ButtonSymbol.  In an ActionML project you should name all of your symbols starting with a capital letter.</p>
<h2>Creating the focus indicator</h2>
<p>To indicate when a button is focused to the user you create an instance inside the button and give it the instance name "focusIndicator".  The focus indicator can be an instance of any symbol as long as you give it the correct instance name.  The focus indicator will be initially hidden by ActionML when your project is played and will be displayed when the user mouses over or tabs to the button.  It will then be hidden again when the user mouses out of or tabs away from the button.  Here is an example of a focus indicator:
<br /><img src="buttons/focus_indicator.png" /><br /></p>
<p>As you can see, the focus indicator looks quite similar to the button but uses a lighter color so the button will "light up" when the user mouses over it.  Note that the focus indicator is given the instance name of "focusIndicator" in the properties palette.  Also note that we are in the same ButtonSymbol as in the previous example, but now we have added an additional layer for the focus indicator.  It is important to make sure that the focus indicator is visible when all layers are not hidden so the user will see it when ActionML makes it visible.
</p>
<h2>Creating the XML</h2>
<p>Now that we have created the button symbol we will place an instance of it on the stage and create the XML to make it interactive.  We will call our instance "basicButton".  In an ActionML project you should start all of your instance names with a lower case letter.  Here is what it looks like in the Flash authoring tool:
<br /><img src="buttons/basic_button.png" /><br /></p>
<p>Note that you can see the focus indicator for the button instance you have created.  This is not an error.  The focus indicator will be hidden by ActionML when your project is run.</p>
<p>Now we will create the XML.  All ActionML XML files start with the ActionML tag just as HTML files start with the html tag.  Inside the ActionML tag w
e need a tag for our button.  There are actually several different ways to do this.  First we will look at an example that uses the Button tag along with the instanceName attribute.  The Button tag tells ActionML to make a button and the instanceName attribute tells ActionML the name of the instance on the stage that it should turn into a button.<p>
<p>All of the XML examples in this documentation are interactive.  They display the XML on the left with the swf on the right.  You can edit the XML to try out various changes and then click the reload button to reload the swf using your edited XML.  Here is what the basic button example looks like:

  <script type="text/javascript">
AC_FL_RunContent( 'codebase','http://download.macromedia.com/pub/shockwave/cabs/flash/swflash.cab#version=9,0,28,0','width','850','height','400','src','InteractionDemo','quality','high','pluginspage','http://www.adobe.com/shockwave/download/download.cgi?P1_Prod_Version=ShockwaveFlash','flashvars','example_swf=buttons/basic_button.swf','movie','InteractionDemo' ); //end AC code
  </script>
  <noscript>
  <object classid="clsid:D27CDB6E-AE6D-11cf-96B8-444553540000" codebase="http://download.macromedia.com/pub/shockwave/cabs/flash/swflash.cab#version=9,0,28,0" width="850" height="400">
    <param name="movie" value="InteractionDemo.swf" />
    <param name="quality" value="high" />
    
	<param name="FlashVars" value="example_swf=buttons/basic_button.swf" />
    <embed src="InteractionDemo.swf" width="850" height="400" quality="high" pluginspage="http://www.adobe.com/shockwave/download/download.cgi?P1_Prod_Version=ShockwaveFlash" type="application/x-shockwave-flash" FlashVars="example_swf=buttons/basic_button.swf"></embed>
  </object>
  </noscript>
</p>
<p>As a shortcut we can simply use the instance name as the tag.  Since the instance name ends with "Button" ActionML is smart enough to know that you want this to be a button.  ActionML can also figure this out if your instance name starts with "button" with a lower case "b" since instance names should start with lower case letters in an ActionML project.  Here is an example using the shortcut:

  <script type="text/javascript">
AC_FL_RunContent( 'codebase','http://download.macromedia.com/pub/shockwave/cabs/flash/swflash.cab#version=9,0,28,0','width','850','height','400','src','InteractionDemo','quality','high','pluginspage','http://www.adobe.com/shockwave/download/download.cgi?P1_Prod_Version=ShockwaveFlash','flashvars','example_swf=buttons/basic_button_instance_shortcut.swf','movie','InteractionDemo' ); //end AC code
  </script>
  <noscript>
  <object classid="clsid:D27CDB6E-AE6D-11cf-96B8-444553540000" codebase="http://download.macromedia.com/pub/shockwave/cabs/flash/swflash.cab#version=9,0,28,0" width="850" height="400">
    <param name="movie" value="InteractionDemo.swf" />
    <param name="quality" value="high" />
    
	<param name="FlashVars" value="example_swf=buttons/basic_button_instance_shortcut.swf" />
    <embed src="InteractionDemo.swf" width="850" height="400" quality="high" pluginspage="http://www.adobe.com/shockwave/download/download.cgi?P1_Prod_Version=ShockwaveFlash" type="application/x-shockwave-flash" FlashVars="example_swf=buttons/basic_button_instance_shortcut.swf"></embed>
  </object>
  </noscript>
</p>

<h2>Creating a dynamic button in the XML</h2>
<p>ActionML can create dynamic instances of symbols in your document.  These are instances that do not exist on the stage in your Flash document.  In order to allow ActionML to create a dynamic instance of a symbol you need to set the symbol properties correctly in the Flash authoring tool.  To set the symbol properties, right click the symbol in the library and select "Properties" from the popup menu as shown here:
<br /><img src="buttons/symbol_properties_menu.png" /><br /></p>
<p>Once you have opened the Symbol Properties window make sure the settings match what you see in the following example.  It is important that you have selected MovieClip for the symbol type, the symbol name matches the Class, and both the "Export for ActionScript" and "Export in first frame" check boxes are checked.  You should be able to simply check the "Export for ActionScript" box and all of the other options will be filled in correctly for you.
<br /><img src="buttons/symbol_properties.png" /><br /></p>
<p>Now the symbol is set up to allow dynamic instances.  In the XML file we can use the same Button tag to create the button but instead of using the instanceName attribute to connect to an existing instance we will use the symbol attribute to tell ActionML to create a dynamic instance of the symbol.  When you create a dynamic instance you should always include a name attribute to tell ActionML what the name of your instance is.  You can also use the x, y, alpha, rotation, color, scaleX, and scaleY attributes or filter attributes to tell ActionML where the button should be placed and how it should look (note: these attributes can also be used with the instanceName attribute to override how the instance looks in the Flash authoring tool).  Let's look at an example that includes a creating a dynamic button instance:
<script type="text/javascript">
AC_FL_RunContent( 'codebase','http://download.macromedia.com/pub/shockwave/cabs/flash/swflash.cab#version=9,0,28,0','width','850','height','400','src','InteractionDemo','quality','high','pluginspage','http://www.adobe.com/shockwave/download/download.cgi?P1_Prod_Version=ShockwaveFlash','flashvars','example_swf=buttons/basic_button_dynamic.swf','movie','InteractionDemo' ); //end AC code
  </script>
  <noscript>
  <object classid="clsid:D27CDB6E-AE6D-11cf-96B8-444553540000" codebase="http://download.macromedia.com/pub/shockwave/cabs/flash/swflash.cab#version=9,0,28,0" width="850" height="400">
    <param name="movie" value="InteractionDemo.swf" />
    <param name="quality" value="high" />

	<param name="FlashVars" value="example_swf=buttons/basic_button_dynamic.swf" />
    <embed src="InteractionDemo.swf" width="850" height="400" quality="high" pluginspage="http://www.adobe.com/shockwave/download/download.cgi?P1_Prod_Version=ShockwaveFlash" type="application/x-shockwave-flash" FlashVars="example_swf=buttons/basic_button_dynamic.swf"></embed>
  </object>
  </noscript>
</p>
<p>Note that the shortcut of starting or ending an instance name with "Button" and skipping the instanceName attribute also works with the symbol attribute.  Since our symbol name in the example is BasicButton we could have used a BasicButton tag and skipped the symbol attribute.</p>
<p>Try experimenting with the x, y, alpha, rotation, color, scaleX, and scaleY attributes for the buttons in the previous example using the Reload button to see the effect of your changes to the XML.</p>

<h2>Making a button respond to a click</h2>
<p>Now that you have explored different ways of creating a button it is time to make the button do something.  This is done by using the click event.  In ActionML there are several ways to make something happen when an event occurs.  The simplest is to use the event attribute.  For the click event that attribute is "onClick" (the attribute for an event is always "on" followed by the name of the event).  Inside an event attribute you can list one or more actions separated by a comma.  For this example we have two overlapping buttons and we use the "moveToFront" action to move a button to the front when it is clicked.
<script type="text/javascript">
AC_FL_RunContent( 'codebase','http://download.macromedia.com/pub/shockwave/cabs/flash/swflash.cab#version=9,0,28,0','width','850','height','400','src','InteractionDemo','quality','high','pluginspage','http://www.adobe.com/shockwave/download/download.cgi?P1_Prod_Version=ShockwaveFlash','flashvars','example_swf=buttons/basic_button_event.swf','movie','InteractionDemo' ); //end AC code
  </script>
  <noscript>
  <object classid="clsid:D27CDB6E-AE6D-11cf-96B8-444553540000" codebase="http://download.macromedia.com/pub/shockwave/cabs/flash/swflash.cab#version=9,0,28,0" width="850" height="400">
    <param name="movie" value="InteractionDemo.swf" />
    <param name="quality" value="high" />

	<param name="FlashVars" value="example_swf=buttons/basic_button_event.swf" />
    <embed src="InteractionDemo.swf" width="850" height="400" quality="high" pluginspage="http://www.adobe.com/shockwave/download/download.cgi?P1_Prod_Version=ShockwaveFlash" type="application/x-shockwave-flash" FlashVars="example_swf=buttons/basic_button_event.swf"></embed>
  </object>
  </noscript>
</p>

<h2>Manipulating other objects when a button is clicked</h2>
<p>Many times you will want a button click to trigger an action on something other than the button itself.  To do this you place the instance name of the object followed by a period followed by the name of the action.  In this example clicking basicButton causes aDynamicButton to move to the front and vice versa.  In other words clicking the front most button will cause the other button to move in front of the button you clicked on.
<script type="text/javascript">
AC_FL_RunContent( 'codebase','http://download.macromedia.com/pub/shockwave/cabs/flash/swflash.cab#version=9,0,28,0','width','850','height','400','src','InteractionDemo','quality','high','pluginspage','http://www.adobe.com/shockwave/download/download.cgi?P1_Prod_Version=ShockwaveFlash','flashvars','example_swf=buttons/basic_button_event2.swf','movie','InteractionDemo' ); //end AC code
  </script>
  <noscript>
  <object classid="clsid:D27CDB6E-AE6D-11cf-96B8-444553540000" codebase="http://download.macromedia.com/pub/shockwave/cabs/flash/swflash.cab#version=9,0,28,0" width="850" height="400">
    <param name="movie" value="InteractionDemo.swf" />
    <param name="quality" value="high" />

	<param name="FlashVars" value="example_swf=buttons/basic_button_event2.swf" />
    <embed src="InteractionDemo.swf" width="850" height="400" quality="high" pluginspage="http://www.adobe.com/shockwave/download/download.cgi?P1_Prod_Version=ShockwaveFlash" type="application/x-shockwave-flash" FlashVars="example_swf=buttons/basic_button_event2.swf"></embed>
  </object>
  </noscript>
</p>

<h2>Opening a URL when a button is clicked</h2>
<p>Making a button move to the front when it is clicked useful once in a while but usually you will want something else to happen.  There are many other actions that can be triggered and they are discussed elsewhere in this documentation.  This next example takes a different path.  Rather than having an action be triggered by the click event we can open a URL by using the "href" attribute on the button.  This works just like it does with links in HTML.  In fact, ActionML is smart enough to know that any time you include an href attribute the item should be a link that opens the specified URL when it is clicked.  You do not even need to use the Button tag.  No matter what tag you use ActionML knows it should be a link (however if you have an item that is just a link and are looking for a tag name to use, ActionML also supports the Link tag).
<script type="text/javascript">
AC_FL_RunContent( 'codebase','http://download.macromedia.com/pub/shockwave/cabs/flash/swflash.cab#version=9,0,28,0','width','850','height','400','src','InteractionDemo','quality','high','pluginspage','http://www.adobe.com/shockwave/download/download.cgi?P1_Prod_Version=ShockwaveFlash','flashvars','example_swf=buttons/basic_button_link.swf','movie','InteractionDemo' ); //end AC code
  </script>
  <noscript>
  <object classid="clsid:D27CDB6E-AE6D-11cf-96B8-444553540000" codebase="http://download.macromedia.com/pub/shockwave/cabs/flash/swflash.cab#version=9,0,28,0" width="850" height="400">
    <param name="movie" value="InteractionDemo.swf" />
    <param name="quality" value="high" />

	<param name="FlashVars" value="example_swf=buttons/basic_button_link.swf" />
    <embed src="InteractionDemo.swf" width="850" height="400" quality="high" pluginspage="http://www.adobe.com/shockwave/download/download.cgi?P1_Prod_Version=ShockwaveFlash" type="application/x-shockwave-flash" FlashVars="example_swf=buttons/basic_button_link.swf"></embed>
  </object>
  </noscript>
Download the fla used by all previous examples <a href="buttons/basic_button.fla">here</a>.
</p>

<h2>Using the focus indicator as a callout</h2>
<p>Another way to use a button is to display a callout when the button is moused over or focused.  In the example below you can see that the focus indicator includes content outside the space of the button itself.  This content is displayed and hidden automatically.
<br /><img src="buttons/callout_button.png" /><br />
<script type="text/javascript">
AC_FL_RunContent( 'codebase','http://download.macromedia.com/pub/shockwave/cabs/flash/swflash.cab#version=9,0,28,0','width','850','height','400','src','InteractionDemo','quality','high','pluginspage','http://www.adobe.com/shockwave/download/download.cgi?P1_Prod_Version=ShockwaveFlash','flashvars','example_swf=buttons/callout_button.swf','movie','InteractionDemo' ); //end AC code
  </script>
  <noscript>
  <object classid="clsid:D27CDB6E-AE6D-11cf-96B8-444553540000" codebase="http://download.macromedia.com/pub/shockwave/cabs/flash/swflash.cab#version=9,0,28,0" width="850" height="400">
    <param name="movie" value="InteractionDemo.swf" />
    <param name="quality" value="high" />

	<param name="FlashVars" value="example_swf=buttons/callout_button.swf" />
    <embed src="InteractionDemo.swf" width="850" height="400" quality="high" pluginspage="http://www.adobe.com/shockwave/download/download.cgi?P1_Prod_Version=ShockwaveFlash" type="application/x-shockwave-flash" FlashVars="example_swf=buttons/callout_button.swf"></embed>
  </object>
  </noscript>
Download the fla for this example <a href="buttons/callout_button.fla">here</a>.
</p>

<h2>Using a hit area</h2>
<p>Most of the time you will want the entire button to be clickable.  Once in a while this will not be the case.  When it is not you can create an instance inside the button called "hit" and this instance will be used to determine what part of the button is clickable.  In the example we have drawn a circle in the left part of the button and filled it with a transparent white color so it won't actually be seen:
<br /><img src="buttons/hit_alpha.png" /><br />
We then name this instance hit:
<br /><img src="buttons/hit.png" /><br />
And the result is that only this circle responds to the mouse:
<script type="text/javascript">
AC_FL_RunContent( 'codebase','http://download.macromedia.com/pub/shockwave/cabs/flash/swflash.cab#version=9,0,28,0','width','850','height','400','src','InteractionDemo','quality','high','pluginspage','http://www.adobe.com/shockwave/download/download.cgi?P1_Prod_Version=ShockwaveFlash','flashvars','example_swf=buttons/hit_button.swf','movie','InteractionDemo' ); //end AC code
  </script>
  <noscript>
  <object classid="clsid:D27CDB6E-AE6D-11cf-96B8-444553540000" codebase="http://download.macromedia.com/pub/shockwave/cabs/flash/swflash.cab#version=9,0,28,0" width="850" height="400">
    <param name="movie" value="InteractionDemo.swf" />
    <param name="quality" value="high" />

	<param name="FlashVars" value="example_swf=buttons/hit_button.swf" />
    <embed src="InteractionDemo.swf" width="850" height="400" quality="high" pluginspage="http://www.adobe.com/shockwave/download/download.cgi?P1_Prod_Version=ShockwaveFlash" type="application/x-shockwave-flash" FlashVars="example_swf=buttons/hit_button.swf"></embed>
  </object>
  </noscript>
Download the fla for this example <a href="buttons/hit_button.fla">here</a>.
</p>

<h2>Including a label in a button</h2>
<p>Often times you will want to create many buttons that are identical to each other but have a text label that is different for each one.  When you want to do this you can create a single button symbol with many instances and use the label attribute in your XML to supply the label for each button.  A button symbol that will include a label needs to have a text field called "labelText" inside it.  This needs to be a dynamic text field.  You should be sure to embed all font characters that might be used in your XML so the label can be displayed correctly.  You will also probably want to turn off selection in the properties palette (using the Ab button).  Most of the time you will also want your label to be a Single line text field.  In order to make sure your button looks good with different labels you should also consider whether the text should be aligned left or in the center.  Here is an example of a button symbol with a label:
<br /><img src="buttons/label_button.png" /><br />
You can also include a "labelText" instance inside a "focusIndicator" to make the label text in a focus indicator match label of the button in its normal state:
<br /><img src="buttons/label_button_focus.png" /><br />
If you place a text field on top of other items in your symbol the cursor will not correctly change to a hand when you mouse over the button.  If you want to ensure the cursor changes to a hand, just place a transparent graphic on the top label of your button.  This could be the "hit" instance if you are using one but does not need to be.  An easy way to do this is to change the color property to Alpha of 0 as in this example:
<br /><img src="buttons/label_button_cover.png" /><br />
Here is the interactive label button example.  Try changing the label in the XML and clicking the reload button to see how easy it is to change the button label.
<script type="text/javascript">
AC_FL_RunContent( 'codebase','http://download.macromedia.com/pub/shockwave/cabs/flash/swflash.cab#version=9,0,28,0','width','850','height','400','src','InteractionDemo','quality','high','pluginspage','http://www.adobe.com/shockwave/download/download.cgi?P1_Prod_Version=ShockwaveFlash','flashvars','example_swf=buttons/label_button.swf','movie','InteractionDemo' ); //end AC code
  </script>
  <noscript>
  <object classid="clsid:D27CDB6E-AE6D-11cf-96B8-444553540000" codebase="http://download.macromedia.com/pub/shockwave/cabs/flash/swflash.cab#version=9,0,28,0" width="850" height="400">
    <param name="movie" value="InteractionDemo.swf" />
    <param name="quality" value="high" />

	<param name="FlashVars" value="example_swf=buttons/label_button.swf" />
    <embed src="InteractionDemo.swf" width="850" height="400" quality="high" pluginspage="http://www.adobe.com/shockwave/download/download.cgi?P1_Prod_Version=ShockwaveFlash" type="application/x-shockwave-flash" FlashVars="example_swf=buttons/label_button.swf"></embed>
  </object>
  </noscript>
Download the fla for this example <a href="buttons/label_button.fla">here</a>.
</p>

</body>
</html>
